TVRD

The TVRD function returns the contents of the specified rectangular portion of the current Direct Graphics window or device. (X₀, Y₀) is the coordinate of the lower left corner of the area to be read and N_x, N_y is the size of the rectangle in columns and rows. The result is a byte array of dimensions N_x by N_y. All parameters are optional. If no arguments are supplied, the entire display device area is read.

Important Note about TVRD and Backing Store

On some systems, when backing store is provided by the window system (the RETAIN keyword to DEVICE or WINDOW is set to 1), reading data from a window using TVRD may cause unexpected results. For example, data may be improperly read from the window even when the image displayed on screen is correct. Having IDL provide the backing store (set the RETAIN keyword to 2) ensures that the window contents will be read properly. More detailed notes about TVRD and the X Window system can be found below in Unexpected Results Using TVRD with X Windows.

Examples

; Read the entire contents of the current display device into the

; variable T:

T = TVRD()

To read from the display to an IDL variable or expression, use the TVRD function with either the CHANNEL parameter or TRUE keyword parameter. The calling sequence for TVRD is:

Result = TVRD([X₀, Y₀, N_x, N_y, Channel])

where (X₀, Y₀) specifies the window coordinate of the lower-left corner of the rectangle to be read, and (N_x, N_y) contains the number of columns and rows to read. Note that all parameters to TVRD are optional. If no arguments are supplied, the entire area of the display device is returned.

When used without the TRUE parameter, TVRD returns an (N_x, N_y) byte image read from the indicated channel. If the channel number is not specified or is zero, the maximum RGB value of each pixel is returned, approximating the luminance.

If present and nonzero, the TRUE keyword indicates that a TrueColor image is to be read and specifies the index of the dimension over which color is interleaved. The result is a (3, N_x, N_y) pixel interleaved array if TRUE is 1; or an (N_x, 3, N_y) line interleaved array if TRUE is 2; or an (N_x, N_y, 3) image interleaved array if TRUE is 3.

Some examples of TVRD follow.

; Read a 512 x 512 image, starting at (0, 0),

; from the red channel into R:

R = TVRD(0, 0, 512, 512, 1)

; Read a TrueColor 512 x 512, line interleaved image,

; starting at (0, 0) into T. The variable T is

; now dimensioned (512, 3, 512):

T = TVRD(0, 0, 512, 512, TRUE = 2)

; Read the maximum RGB value of each pixel into L:

L = TVRD(0, 0, 512, 512)

Syntax

Result = TVRD( [X₀ [, Y₀ [, N_x [, N_y [, Channel]]]]] [, CHANNEL=value] [, /ORDER] [, TRUE={1 | 2 | 3}] [, /WORDS] )

Return Value

Returns a byte array of the specified dimensions.

Arguments

X₀

The starting column of data to read. The default is 0.

Y₀

The starting row of data to read. The default is 0.

N_x

The number of columns to read. The default is the width of the display device or window less X₀.

N_y

The number of rows to read. The default is the height of the display device or window less Y₀.

Channel

The memory channel to be read. If not specified, this argument is assumed to be zero. This parameter is ignored on display systems that have only one memory channel.

Keywords

CHANNEL

The memory channel to be read. The CHANNEL keyword is identical to the optional Channel argument.

Note: If the display is a 24-bit display, and both the CHANNEL and TRUE parameters are absent, the maximum RGB value in each pixel is returned.

ORDER

Set this keyword to override the current setting of the !ORDER system variable for the current image only. If set, it causes the image to be read from the top down instead of the normal bottom up.

TRUE

If this keyword is present, it indicates that a TrueColor image is to be read, if the display is capable. The value assigned to TRUE specifies the index of the dimension over which color is interleaved. The result is an (3, n_x, n_y) pixel-interleaved array if TRUE is 1; or an (n_x, 3, n_y) line-interleaved array if TRUE is 2; or an (n_x, n_y, 3) image-interleaved array if TRUE is 3.

Note: IDL returns the MAX of the three channels when you do TVRD without setting TRUE on a TrueColor system.

WORDS

Set this keyword to indicate that words are to be transferred from the device. This keyword is valid only when using devices that can transfer 16-bit pixels. The normal transfer uses 8-bit pixels. If this keyword is set, the function result is an integer array.

Unexpected Results Using TVRD with X Windows

When using TVRD with the X Windows graphics device, there are two unexpected behaviors that can be confusing to users:

When reading from a window that is obscured by another window (i.e., the target window has another window “on top” or “in front” of it, or one window overlaps the target), TVRD may return the contents of the window in front as part of the image contained in the target window.
When reading from an iconified window, the X server may return a stream of “BadMatch” protocol events.

IDL uses the Xlib function XGetSubImage() to implement TVRD. The following quote is from the documentation for XGetSubImage() found in The X Window System by Robert W. Scheifler and James Gettys, Second Edition, page 174. It explains the reasons for the behaviors described above:

“If the drawable is a window, the window must be viewable, and it must be the case that if there were no... overlapping windows, the specified rectangle of the window would be fully visible on the screen, ... or a BadMatch error results. If the window has backing-store, then the backing-store contents are returned for regions of the window that are obscured... If the window does not have backing-store, the returned contents of such obscured regions are undefined.”

Hence, the first behavior is caused by attempting to use TVRD on an obscured window that does not have backing store provided by the X server. The result in this case is undefined, meaning that the different servers can produce entirely different results. Many servers return the image of the obscuring window.

The second behavior is caused by attempting to read from a non-viewable (i.e., unmapped) window. Although IDL could refuse to allow TVRD to work with unmapped windows, some X servers return valid and useful results. Therefore, TVRD is allowed to attempt to read from unmapped windows.

Both of these behavior problems can be solved by using one of the following methods:

Always make sure that your target window is mapped and is not obscured before using TVRD on it. The following IDL command can be used:

WSET, Window_Index

Make IDL provide backing store (rather than the window system) by setting the RETAIN keyword to DEVICE or WINDOW equal to 2.

Note that under X Windows, backing store is a request that may or may not be honored by the X server. Many servers will honor backing store for 8-bit visuals but ignore them for 24-bit visuals because they require three times as much memory.

Version History

Original

Introduced